<html>
<link href="../enzo.css" rel="stylesheet" type="text/css">
  <head>
    <title>Data Analysis</title>
  </head>
<body> 
    <h1>Data Analysis</h1>

    <p>Data analysis in Enzo can be complicated.  There are excellent premade packages 
      available for doing Enzo data analysis (see the appropriate 
      <a href="../amr_guide/analyze.html">Section</a> in the Enzo manual).  However, 
      it is likely that your data analysis needs will grow beyond these tools.

    <h2>HDF 5 Tools</h2>
    <p>Enzo reads in initial conditions files and outputs simulation data using the 
      <a href="http://hdf.ncsa.uiuc.edu/HDF5/">HDF 5</a> structured data format (created and 
      maintained by the <a href="http://hdf.ncsa.uiuc.edu/">NCSA HDF group</a>).  Though this 
      format takes a bit more effort to code than pure C/C++ binary output, we find that the
      advantages are worth it.  Unlike raw binary, HDF 5 is completely machine-portable and 
      the HDF 5 library takes care of error checking.  There are many useful standalone
      utilities included in the HDF 5 package that allow a user to examine the contents and 
      structure of a dataset.  In addition, there are several visualization and data analysis
      packages that are HDF 5-compatible.  See the page on <a href="dataviz_top.html">Data
	Vizualization</a> for more information about this.
      The NCSA HDF group has an excellent 
      <a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/Tutor/">tutorial</a> on working
      with HDF 5.</p>

    <p>Note that as of the February 2004 code release, Enzo still supports the
      <a href="http://hdf.ncsa.uiuc.edu/hdf4.html">HDF 4</a> data format.  We strongly
      suggest that new users completely avoid this and use the HDF 5 version instead.
      Enzo's parallel IO only works with HDF 5, and subsequent releases of Enzo will
      not have any legacy support for HDF 4 at all.</p>




    <h2>Writing your own tools, I - the Enzo Grid Hierarchy</h2>
    <p>Enzo outputs each individual adaptive mesh block as its own grid file.  Each of these
      files is completely self-contained, and has information about all of the grid cells
      that are within that volume of space.  Information on the size and spatial location of a
      given grid file can be obtained from the hierarchy file, which has the file extension
      ".hierarchy".  This ascii file has a listing for each grid that looks something like this:

<pre>
Grid = 26
GridRank          = 3
GridDimension     = 34 22 28 
GridStartIndex    = 3 3 3 
GridEndIndex      = 30 18 24 
GridLeftEdge      = 0.5 0.28125 0.078125 
GridRightEdge     = 0.71875 0.40625 0.25 
Time              = 101.45392321467
SubgridsAreStatic = 0
NumberOfBaryonFields = 5
FieldType = 0 1 4 5 6 
BaryonFileName = RedshiftOutput0011.grid0026
CourantSafetyNumber    = 0.600000
PPMFlatteningParameter = 0
PPMDiffusionParameter  = 0
PPMSteepeningParameter = 0
NumberOfParticles   = 804
ParticleFileName = RedshiftOutput0011.grid0026
GravityBoundaryType = 2
Pointer: Grid[26]->NextGridThisLevel = 27
</pre>
      
    <p><tt>GridRank</tt> gives the dimensionality of the grid (this one is 3D),
      <tt>GridDimension</tt> gives the grid size in grid cells, including ghost zones.
      <tt>GridStartIndex</tt> and <tt>GridEndIndex</tt> give the starting and ending indices
      of the non-ghost zone cells, respectively.  The total size of the baryon datasets in each
      grid along dimension i is (1+ <tt>GridEndIndex[i]</tt> - <tt>GridStartIndex[i]</tt>).  
      <tt>GridLeftEdge</tt> and <tt>GridRightEdge</tt> give the physical edges of the grids 
      (without ghost zones) in each dimension.  <tt>NumberOfParticles</tt> gives the number of
      dark matter particles (and/or star particles, for simulations containing star particles) in a 
      given grid.  Note that when there are multiple grids covering a given region of space at various
      levels of resolution, particles are stored in the most highly refined grid.  <tt>BaryonFileName</tt>
      is the name of the actual grid file, and should be the same as <tt>ParticleFileName</tt>.  <tt>Time</tt> 
      is the simulation time, and should be the same as <tt>InitialTime</tt> in the parameter file for the 
      same data dump.</tt>  The other parameters for each entry are more advanced and probably not relevant
      for simple data analysis.</p>

    <p>Possibly the greatest source of potential confusion in Enzo's datasets is the overlap of grid cells.  In a 
    simulation, when a given grid is further refined, the coarse cells which have not been refined are still 
    kept.  The solution to the hydro and gravity equations are still calculated on that level, but are updated
    with information from more highly refined levels.  What this is means is that a volume of space which has
    been refined beyond the root grid is covered by multiple grid patches at different levels of resolution.
    Typically, when doing analysis you only want the most highly refined information for a given region of space
    (or the most highly refined up to a certain level) so that you don't double-count (or worse) the gas in 
    a given cell.  Look at this <a href="example_analysis_code.tar.gz">example analysis code</a>
    </p>


    <h2>Writing your own tools, II - Enzo Physical Units</h2>
    <p>Yet another significant source of confusion is the units that Enzo uses.  When doing a cosmology simulation,
      the code uses a set of units that make most quantities on the order of unity (in principle).  The Enzo manual
      section on <a href="../amr_guide/output.html">the code output format</a> explains how to convert code units
      to cgs units.  However, there are some subtleties:</p>

    <p><b>Density fields</b>:  All density fields are in the units described in the amr guide <b>except</b>
      electron density.  Electron density is only output when <tt>MultiSpecies</tt> is turned on, and in order to
      convert the electron density to cgs it must be multiplied by the code density conversion factor and then 
      (m_e/m_p), where m_e and m_p are the electron and proton rest masses (making electron density units 
      different from the other fields by a factor of m_e/m_p).  The reason this is done is so that in the 
      code the electron density can be computed directly from the abundances of the ionized species.</p>

      
    <p><b>Energy fields</b>:  There are two possible energy fields that appear in the code - Gas energy and 
      total energy.  Both are in units of <b>specific energy</b>, ie, energy per unit mass.  
      When Zeus hydro is being used (<tt>HydroMethod = 2</tt>, there should be only one energy field - 
      "total energy".  This is a misnomer - the Zeus hydro method only follows the specific internal (ie,
      thermal) energy of the gas explicitly.  When the total energy is needed, it is calculated from the
      velocities.  When PPM is used (<tt>HydroMethod = 0</tt>) the number of energy fields
      depends on whether or not <tt>DualEnergyFormalism</tt> is turned on or off.  If it is ON (1), 
      there is a "gas energy" field and a "total energy" field, where "gas energy" is the specific internal
      energy and "total energy" is "gas energy" plus the specific kinetic energy of the gas in that cell.
      If <tt>DualEnergyFormalism</tt> is OFF (0), there should only be "total energy", which is kinetic+internal
      specific energies.  Confused yet?
    </p>
    
    <p><b>Particle mass field</b>:  Particle "masses" are actually stored as densities.  This is to facilitate
      calculation of the gravitational potential.  The net result of this is that, in order to calculate the 
      stored particle "mass" to a physical mass, you must first multiply by the volume of a cell on the grid
      that the particle is stored in, and then convert to CGS.  Grid cells are cubic, so pick your favorite
      axis and get the length of one grid cell in code units, which is equal to  
      (<tt>GridRightEdge</tt>-<tt>GridLeftEdge</tt>) / (1+<tt>GridEndIndex</tt>-<tt>GridStartIndex</tt>).  
      Don't forget to convert both the volume and density to CGS units!</p>

    </p>

<p>&nbsp;</p>
<p>
<a href="dataissues_top.html">Previous - Data Handling Issues</a><br>
<a href="dataviz_top.html">Next - Data Visualization</a><br>
</p>

<p>&nbsp;</p>
<p>
<a href="../index.html">Go to the Enzo home page</a>
</p>
<hr WIDTH="100%">
<center>&copy; 2004 &nbsp; <a href="http://cosmos.ucsd.edu">Laboratory for Computational Astrophysics</a><br></center>
<center>last modified February 2004<br>
by <a href="mailto:bwoshea (AT) lanl.gov">B.W. O'Shea</a></center>

</body>
</html>
